URI

/trustedx-resources/esigp/v1/sign_identities/{sign_identity_id}

Description

Resource containing information on specific signature keys (e.g., the X.509 certificate for these keys, the labels that allow selecting these keys, etc.). Depending on where the private part of the keys to which a signing identity refers to is located, a distinction is made between:

Signing identity on server: the private part of the keys is stored in a TRIDENT signature provider (typically, in an HSM the platform as access to).
Signing identity on mobile device: the private part of the keys is held in a mobile device (e.g., a smart phone).

Representation

A signing identity is represented in JSON as follows:

{
    "id" : {string},
    "self" : {string},
    "description" : {string},
    "labels" : [ {string} ],
    "type" : {string},
    "device_id" : {string},
    "domain" : {string},
    "access" : [ {
        "user_id" : {string},
        "permissions": [ {string} ]
    } ],
    "details" : {
        "certificate" : {string},
        "activation_mode": {string},
        "public_key" : {string}
    },
    "links" :  {
        <operation_alias> : {
            "auth" : {
                "oauth2": {
                    "scopes": [ {string} ]
                }
            }
        }    
	},
    "status" : {
        "value" : {string},
        "reason" : {string}
    }
}

Property	Description
`id`	Identifier of the signing identity.
`self`	Access URL for the signing identity.
`description`	Description of the signing identity.
`labels[]`	List of labels associated to the signing identity.
`type`	Type of signing identity. This property currently always takes the `pki:x509` value.
`device_id`	Device where the private part of the keys associated to the signing identity is located. Only the signing identities on mobile devices have this property.
`domain`	Domain the signing identity belongs to.
`access[]`	Information on access control to the signing identity.
`access[].user_id`	Identifier of a user with access to the signing identity.
`access[].permissions`	Access permissions of a user to the signing identity. The permissions can be one or more of the following: `manage`: permission for managing the signing identity (update, disable, enable, query access permissions, change access permissions, etc.) but not for creating a signature with the key associated with the signing identity. `sign`: permission for creating a signature with the key associated with the signing identity. `assign_for_signing`: permission for self-granting the `sign` permission on the signing identity. This permission is for implementing the granting of the `sign` permission in two steps: in the first step, the user receives the `assign_for_signing` permission from the user with the `manage` permission; in the second, the user self-grants the `sign` permission by using the `assign_for_signing` permission.
`details`	Details for implementing the signing identity.
`details.certificate`	X.509 certificate encoded in DER and base64. Only `pki:x509` signing identities have this property.
`details.activation_mode`	Activation mode of the signing identity. Only server-signing identities have this property, and it can take the following values: `"trustedx"`: the signing identity is activated by the authentication of its owner performed by the TRIDENT. `"hsm-pwd"`: the signature identity is activated by a password entered by the owner and validated by the HSM.
`details.public_key`	The public part of the keys associated with the signing identity. `PublicKeyInfo` ASN.1 structure encoded in DER and base64. Only `pki:x509` signing identities have this property.
`links`	Information on operations that use the signing identity.
`links.<operation_alias>`	Information on the `<operation_alias>` operation regarding the use of the signing identity. Currently, the only value possible of `<operation_alias>` is `Signatures.create.server.raw`.
`links.<operation_alias>.auth`	Authorization information on the `<operation_alias>` operation regarding the use of the signing identity.
`links.<operation_alias>.auth.oauth2`	OAuth 2.0 authorization information on the `<operation_alias>` operation regarding the use of the signing identity.
`links.<operation_alias>.auth.oauth2.scopes[]`	Set of OAuth 2.0 scopes required for accessing the `<operation_alias>` operation so that this operation can use the signing identity.
`status`	Information on the status of the signing identity.
`status.value`	Status of the signing identity. `"enabled"`: The signing identity is enabled. `"disabled"`: The signing identity is disabled. `"locked"`: The signing identity is locked. Note A signing identity is always created in the `enabled` status. The only status transitions possible are from `enabled` to `disabled`, `disabled` to `enabled` and `enabled` to `locked`. The first two transitions are performed by executing the Enable or disable a signing identity operation. The third is only possible for signing identities enabled by an HSM password. This transition only occurs after 15 consecutive failed enabling attempts. I.e., the user provides an incorrect enabling password 15 times in a row.
`status.reason`	The reason why the signing identity is in its current state. This property is optional and normally indicates why a signing identity has been locked or disabled.

Access Permissions to a Signing Identity

A signing identity schema can allow the server signing identities of a group to be used by multiple users. This might be necessary, for example, if the signing identities of this group are for legal persons (if an organization owns the signing identity) and natural persons (users) are required to create signatures with them (e.g., to create electronic seals). In these cases, it can be useful if several users have signing identity access permissions.

In contrast, when a signing identity is for a natural person, i.e., when the signing identity is owned by a user (always for mobile signing identities), only this user should have access to the signing identity.

These circumstances are configured by the TRIDENT administrator when registering the signing identity schemas in the system.

In general, from the point of view of the signing identities API, the following are the access permissions a user can have to a signing identity.

manage: allows updating the signing identity access permissions (if the group the identity is part of allows it). I.e., granting and revoking the permissions of any user. It also allows updating, enabling , and disabling signing identities.
sign: allows using the signing identity to create signatures.
assign_for_signing: lets the user self-grant the sign permission on a signing identity.

When a signing identity is created, the only user given access permissions to the signing identity is the user who authorized the identity's creation (i.e., the user on whose behalf the signing identity was created). The permissions obtained by this user are manage and sign.

Subsequently, if the schema allows it, other users may obtain access permissions to the signing identity if the user with the manage permission (initially only the user that created the identity) grants it to them. As stated above, this option is for when the owner of a signing identity is a legal person (an organization) and not a natural person.

The set of permissions users have on a signing identity is called the signing identity's Access Control List (ACL).

Granting of the sign permission can be done in two ways:

Directly (direct sharing): a user with the manage permission updates the signing identity access permissions to grant the sign permission to another user.
In two steps (two-phase key sharing): a user with the manage permission updates the signing identity access permissions to grant the assign_for_signing permission to another user. Subsequently, this other user updates their access permissions to the signing identity by self-granting the sign permission. The second step can be seen as an acceptance by the user of the permission to sign with a signing identity.

The option of sharing signing identities and the option or requirement to grant the sign permissions on these identities in two steps is configured by the TRIDENT administrator when registering the signing identity schemas in the system. As a result, in some signing identity groups, the sharing of signing identities may be allowed, while in others, it may not. Likewise, in some signing identity groups, sharing in two steps may be optional, while in others, it may be required.

URI

Description

Representation

Access Permissions to a Signing Identity

Operations